﻿@page "/docs/components/link"

<Seo Canonical="/docs/components/link" Title="Blazorise Link system" Description="The Link component allows you to easily customize anchor elements with your theme colors and typography styles." />

<DocsPageTitle Path="Components/Link">
    Blazorise Link component
</DocsPageTitle>

<DocsPageLead>
    Provides declarative, accessible navigation around your application.
</DocsPageLead>

<DocsPageParagraph>
    The <Code Tag>Link</Code> component allows you to easily customize anchor elements with your theme colors and typography styles.
    Link is the building block for most Blazorise components that offer link functionality. A <Code>Link</Code> component behaves
    like an <Code Tag>a</Code> element, except it toggles an active CSS class based on whether its <Code>href</Code> matches the
    current URL.
</DocsPageParagraph>

<Alert Color="Color.Info" Visible>
    <AlertDescription>
        <Strong>Note:</Strong> due to a <Blazorise.Link To="https://github.com/dotnet/razor-tooling/issues/5527">bug</Blazorise.Link>
        in VisualStudio tooling you should write <Code Tag>Link</Code> as <Code Tag>Blazorise.Link</Code> until the issue is resolved.
        Or if you prefer the alternative, you can also use the <Code Tag>Anchor</Code> alias.
    </AlertDescription>
</Alert>

<DocsPageSubtitle>
    Examples
</DocsPageSubtitle>

<DocsPageSection>
    <DocsPageSectionHeader Title="Basic">
        By specifying a value in the <Code>To</Code> property, a standard link (<Code Tag>a</Code>) element will be rendered.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <BasicLinkExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="BasicLinkExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Anchor Links">
        A <Code>#</Code> in front of a link location specifies that the link is pointing to an anchor on a page.
        (Anchor meaning a specific place in the middle of your page).

        Typically <Code Tag>a href="#"</Code> will cause the document to scroll to the top of page when clicked.
        <Code Tag>Link</Code> addresses this by preventing the default action (scroll to top) when <Code>To</Code> is set to <Code>#</Code>.
        If you need scroll to top behavior, use a standard <Code Tag>Link To="#"&gt;...&lt;/Link</Code> tag.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <AnchorLinkExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="AnchorLinkExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Target">
        If you want to open link in a new tab or window you can use the <Code>Target</Code> parameter.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <LinkTargetExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="LinkTargetExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Target iframe">
        By assigning a name to a frame via the name attribute, you can refer to it as the "target" of links defined by other elements. Our <Code>Target</Code> parameter can also accept string values.
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="CustomLinkTargetExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Stretched link">
        <Paragraph>
            Add <Code>Stretched</Code> attribute to a link to make its containing block clickable via a <Code>::after</Code> pseudo element. In most cases, this means that an element with <Code>position: relative</Code> that contains a link with the stretched link class is clickable. Please note given how CSS position works, stretched-link cannot be mixed with most table elements.
        </Paragraph>
        <Paragraph>
            Cards have <Code>position: relative</Code> by default, so in this case you can safely add the <Code>Stretched</Code> attribute to a link in the card without any other HTML changes.
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <LinkStretchedExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="LinkStretchedExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Disabled link">
        <Paragraph>
            Make links look inactive by adding the <Code>Disabled</Code> boolean attribute to any <Code Tag>Link</Code> element.
        </Paragraph>
        <Paragraph>
            <Alert Visible Color="Color.Info">
                The disabled class uses <Code>pointer-events: none</Code> to try to disable the link functionality of <Code Tag>a</Code>s, but that CSS property is not yet standardized. In addition, even in browsers that do support <Code>pointer-events: none</Code>, keyboard navigation remains unaffected, meaning that sighted keyboard users and users of assistive technologies will still be able to activate these links. So to be safe, add a <Code>tabindex="-1"</Code> attribute on these links (to prevent them from receiving keyboard focus) and use custom JavaScript to disable their functionality.
            </Alert>
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <LinkDisabledExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="LinkDisabledExample" />
</DocsPageSection>

<DocsPageSubtitle>
    API
</DocsPageSubtitle>

<Heading Size="HeadingSize.Is3">
    Attributes
</Heading>

<DocsAttributes>
    <DocsAttributesItem Name="To" Type="string" Default="null">
        Specifies that multiple files can be selected.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Target" Type="Target" Default="Default">
        The target attribute specifies where to open the linked document.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Match" Type="Match" Default="Prefix">
        URL matching behavior for a link.
    </DocsAttributesItem>
    <DocsAttributesItem Name="CustomMatch" Type="Func<string, bool>" Default="null">
        A callback function that is used to compare current uri with the user defined uri. Must enable <Code>Match="Match.Custom"</Code> to be used.
    </DocsAttributesItem>
    <DocsAttributesItem Name="CustomMatch" Type="Func<string, bool>" Default="null">
        A callback function that is used to compare current uri with the user defined uri. Must enable <Code>Match.Custom</Code> to be used.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Title" Type="string" Default="null">
        Defines the title of a link, which appears to the user as a tooltip.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Unstyled" Type="bool" Default="false">
        Removes default color styles from the link.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Clicked" Type="EventCallback">
        Occurs when the link is clicked.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Stretched" Type="bool" Default="false">
        Makes any HTML element or component clickable by “stretching” a nested link.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Disabled" Type="bool" Default="false">
        Makes the link look inactive by adding the disabled boolean attribute.
    </DocsAttributesItem>
</DocsAttributes>